# Microsoft Teams
The PMG Microsoft Teams (Teams) Connector provides various management and interactivity transactions with the Teams service. The connector supports connectivity to Teams by defining a scenario for each target Teams environment. With a defined scenario, the Teams actions can then be used to perform various transactions with the Teams service.
# Teams Scenarios
To define scenarios for Teams, begin by accessing the Teams Scenario management screen either from Administration, Connectors, Microsoft Teams, or, from Workflow Designer, Manage, Connector Configuration, Microsoft Teams.
From the initial screen, define a new scenario by name and the settings management for the scenario will display as above. Provide values for each of the inputs to establish a connection to the respective Teams scenario. Once defined, this scenario name may be used by any of the Teams Workflow Actions.
Authentication:
The Teams connector uses access tokens to authenticate to the Graph API. First, an app must be registered in the Azure portal. Registering an app integrates it with the Microsoft identity platform and allows the retrieval of access tokens. The app needs to be assigned permissions to allow the connector to use the endpoints. The app will have an application ID, redirect URL, and application secret.
The Client ID maps to the Application (client) ID field and the Tenant ID maps to the Directory (tenant) ID field of the Azure application. The Client Secret is that of the Azure application. Generally, the connector uses the Auth Type “Auth Code” which is needed when the endpoint requires a delegated permission type. Some endpoints support an Application permission type, which can use a scenario with the “Client Credentials” Auth Type. Currently, all of the connector actions support an “Auth Code” endpoint.
To generate the Refresh Token, the redirect URI needs to be set to:
https://[portal-hostname] /spe/OAuth/GraphApi
Navigate to this endpoint, fill out the required fields and click “Authorize API.” An access code will be retrieved from Microsoft. Fill out the required information again and click “Request Access Token.” An access token and refresh code will be returned. Copy the refresh code to use as the refresh token in the connector configuration.
# Teams Workflow Actions
# Add Team Member
Action Function:
The Add Team Member action will add a new team member to a named Team.
Action Properties:
Scenario: The connection scenario to use for the action
Team ID: The Team ID to add the user
User type: The team member type to set for the user for the team. To set this type dynamically, use the provided edit option for this value. If required, the base action definition may be modified for additional types with additional choice properties. See Manage, Actions, Microsoft Teams, Add Team Member.
<property name="userType" realName="@odata.type" displayname="User Type" type="select" defaultvalue="#microsoft.graph.aadUserConversationMember" jsonField="true" mandatory="true">
<choice>Team Member;#microsoft.graph.aadUserConversationMember</choice>
</property>
Roles: A comma separated list of roles for the user
User URL: The Graph API user identifier URL, aka the "user@odata.bind" property, e.g.
https://graph.microsoft.com/v1.0/users('jacob@contoso.com')
Web timeout: An override timeout time in seconds to use for the call
Response variable: A variable to hold the response from the call
Error message variable: A variable to hold the error information from the call
Action Outputs:
Success
Failure
# Create a Team
Action Function:
The Create a Team action will create a new Teams within the Teams service.
Action Properties:
Scenario: The connection scenario to use for the action
Team Template: The team template to apply for the new team
Display Name: The display name for the team
Description: A description for the team
Members: The members to add to the team. This property allows for one or more members to be added at a time. Each member added provides inputs for the following: Type, Roles, User URL.
Type: The team member type to set for the user for the team. If required, the base action definition may be modified for additional types with additional option properties. See Manage, Actions, Microsoft Teams, Create a Team.
<property name="members" displayname="Members" type="table" jsonField="true">
<fields includeWorkflowVariables="true" movablerows="true">
<field mandatory="true" name="Type" realName="@odata.type" type="select">
<option value="#microsoft.graph.aadUserConversationMember">Member</option>
</field>
<field mandatory="true" name="Roles" realName="roles" type="text" autocomplete="true" jsonType="string array"></field>
<field mandatory="true" name="User URL" realName="user@odata.bind" type="text" autocomplete="true"></field>
</fields>
</property>
Roles: a comma separated list of roles
User URL: The Graph API user identifier URL, aka the "user@odata.bind" property, e.g. "https://graph.microsoft.com/v1.0/users('jacob@contoso.com')"
Web timeout: An override timeout time in seconds to use for the call
Response variable: A variable to hold the response from the call
Error message variable: A variable to hold the error information from the call
Action Outputs:
Success
Failure
# Create a Team from a Group
Action Function:
The Create a Team from a Group action will generate a team from a group definition.
Action Properties:
Scenario: The connection scenario to use for the action
Group ID: The Group ID to use for the Team creation
Allow Private Channels: Determines if private channels are allowed for the Team
Allow Users to Edit Messages: Determines if users are allowed to edit messages
Allow Giphy: Determines if Giphy is enabled for the Team
Giphy Content Rating: Sets the content rating for the Giphy feature
Web timeout: An override timeout time in seconds to use for the call
Response variable: A variable to hold the response from the call
Error message variable: A variable to hold the error information from the call
Action Outputs:
Success
Failure
# Create Channel
Action Function:
The Create Channel action will create a channel for a Team.
Action Properties:
Scenario: The connection scenario to use for the action
Team ID: The Team ID to use for the channel
Channel display name: The display name for the channel
Channel description: A description for the channel
Web timeout: An override timeout time in seconds to use for the call
Response variable: A variable to hold the response from the call
Error message variable: A variable to hold the error information from the call
Action Outputs:
Success
Failure
# Get Channel
Action Function:
The Get Channel action read the details of a channel for a Team.
Action Properties:
Scenario: The connection scenario to use for the action
Team ID: The Team ID to use for the channel
Channel ID: The channel ID to read
Web timeout: An override timeout time in seconds to use for the call
Request status variable: A variable to hold the request status from the call
Response variable: A variable to hold the channel details response from the call. An example response is below.
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#teams('3082e20f-7b75-4465-b5e2-f76d1cf42a20')/channels/$entity",
"id": "19:4bd8ed00bcb34f408351bb10be5fd3b7@thread.tacv2",
"createdDateTime": "2021-02-10T13:33:56.453Z",
"displayName": "General",
"description": "Test a connector",
"isFavoriteByDefault": null,
"email": "",
"webUrl": "https://teams.microsoft.com/l/channel/19%3a4bd8ed00bcb34f408351bb10be5fd3b7%40thread.tacv2/General?groupId=3082e20f-7b75-4465-b5e2-f76d1cf42a20&tenantId=bb506fc1-8dec-422f-a2ff-5447575f1f78",
"membershipType": "standard"
}
Error message variable: A variable to hold the error information from the call
Action Outputs:
Success
Failure
# Get Groups
Action Function:
The Get Groups action will return matching groups for a given query.
Action Properties:
Scenario: The connection scenario to use for the action
Filter Value: The filter value to use to search for groups
Properties to return: a comma separated list of properties to return for the matched groups
Order by: A field to use in the response ordering
Max Count: The maximum number of matches to return
Web timeout: An override timeout time in seconds to use for the call
Response variable: A variable to hold the group details response from the call. An example is below.
{
"value": [
{
"id": "3082e20f-7b75-4465-b5e2-f76d1cf42a20",
"displayName": "SampleGroup",
"description": "Test a connector"
}
],
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups(id,displayName,description)"
}
Error message variable: A variable to hold the error information from the call
Action Outputs:
Success
Failure
# Get Team
Action Function:
The Get Team action will return details of a specified Team.
Action Properties:
Scenario: The connection scenario to use for the action
Team ID: The Team ID to use for the channel
Properties to return: a comma separated list of properties to return for the matched groups
Web timeout: An override timeout time in seconds to use for the call
Order by: A field to use in the response ordering
Max Count: The maximum number of matches to return
Web timeout: An override timeout time in seconds to use for the call
Request status variable: A variable to hold the request status from the call
Response variable: A variable to hold the Team details response from the call
Error message variable: A variable to hold the error information from the call
Action Outputs:
Success
Failure
# Get Users
Action Function:
The Get Users action will return matching users for a given query.
Action Properties:
Scenario: The connection scenario to use for the action
Filter Value: The filter value to use to search for groups. An example query is below
startswith(displayName, 'V{{UserName}}')
Properties to return: a comma separated list of properties to return for the matched groups. An example is below
id,displayName,description
Order by: A field to use in the response ordering
Max Count: The maximum number of matches to return
Web timeout: An override timeout time in seconds to use for the call
Response variable: A variable to hold the channel details response from the call. An example response is below.
{
"value": [
{
"givenName": "Jan",
"jobTitle": null,
"mail": "jdes@pmg.net",
"mobilePhone": null,
"officeLocation": null,
"preferredLanguage": null,
"surname": "Des",
"userPrincipalName": "jdes@pmg.net",
"displayName": "Jan Des",
"id": "07cba107-eacb-4b1d-9e5e-68c9a47c9583"
},
{
"givenName": "Jean",
"jobTitle": null,
"mail": "jwebster@pmg.net",
"mobilePhone": null,
"officeLocation": null,
"preferredLanguage": null,
"surname": "Webster",
"userPrincipalName": "jwebster@pmg.net",
"displayName": "Jean Webster",
"id": "e37528ea-7b12-49f1-84a5-00ebcf7833d8"
}
]
}
Error message variable: A variable to hold the error information from the call
Action Outputs:
Success
Failure
# Get User's Teams
Action Function:
The Get User's Teams action will return Teams for a specified user.
Action Properties:
Scenario: The connection scenario to use for the action
User ID: The user ID to use to return teams
Web timeout: An override timeout time in seconds to use for the call
Request status variable: A variable to hold the request status from the call
Response variable: A variable to hold the channel details response from the call
Error message variable: A variable to hold the error information from the call
Action Outputs:
Success
Failure
# List Channel Messages
Action Function:
The List Channel Messages action will return a list of messages for a specified channel.
Action Properties:
Scenario: The connection scenario to use for the action
Team ID: The Team ID to retrieve messages
Channel ID: The Channel ID to retrieve messages
Max Count: The max count of messages to return
Web timeout: An override timeout time in seconds to use for the call
Request status variable: A variable to hold the request status from the call
Response variable: A variable to hold the messages response from the call. An example response is below.
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#teams('3082e20f-7b75-4465-b5e2-f76d1cf42a20')/channels('19%3A4bd8ed00bcb34f408351bb10be5fd3b7%40thread.tacv2')/messages",
"@odata.count": 5,
"value": [
{
"id": "1629206444908",
"replyToId": null,
"etag": "1629206444908",
"messageType": "message",
"createdDateTime": "2021-08-17T13:20:44.908Z",
"lastModifiedDateTime": "2021-08-17T13:20:44.908Z",
"lastEditedDateTime": null,
"deletedDateTime": null,
"subject": null,
"summary": null,
"chatId": null,
"importance": "normal",
"locale": "en-us",
"webUrl": "https://teams.microsoft.com/l/message/19%3A4bd8ed00bcb34f408351bb10be5fd3b7%40thread.tacv2/1629206444908?groupId=3082e20f-7b75-4465-b5e2-f76d1cf42a20&tenantId=bb506fc1-8dec-422f-a2ff-5447575f1f78&createdTime=1629206444908&parentMessageId=1629206444908",
"policyViolation": null,
"eventDetail": null,
"from": {
"application": null,
"device": null,
"user": {
"id": "8461648c-bbdf-4348-b48b-feceafd2b8bc",
"displayName": "Christy Hilley",
"userIdentityType": "aadUser"
}
},
"body": {
"contentType": "text",
"content": "This is a test"
},
"channelIdentity": {
"teamId": "3082e20f-7b75-4465-b5e2-f76d1cf42a20",
"channelId": "19:4bd8ed00bcb34f408351bb10be5fd3b7@thread.tacv2"
},
"attachments": [],
"mentions": [],
"reactions": []
},
{
"id": "1612983934706",
"replyToId": null,
"etag": "1612983934706",
"messageType": "unknownFutureValue",
"createdDateTime": "2021-02-10T19:05:34.706Z",
"lastModifiedDateTime": "2021-02-10T19:05:34.706Z",
"lastEditedDateTime": null,
"deletedDateTime": null,
"subject": null,
"summary": null,
"chatId": null,
"importance": "normal",
"locale": "en-us",
"webUrl": "https://teams.microsoft.com/l/message/19%3A4bd8ed00bcb34f408351bb10be5fd3b7%40thread.tacv2/1612983934706?groupId=3082e20f-7b75-4465-b5e2-f76d1cf42a20&tenantId=bb506fc1-8dec-422f-a2ff-5447575f1f78&createdTime=1612983934706&parentMessageId=1612983934706",
"from": null,
"policyViolation": null,
"body": {
"contentType": "html",
"content": "<systemEventMessage/>"
},
"channelIdentity": {
"teamId": "3082e20f-7b75-4465-b5e2-f76d1cf42a20",
"channelId": "19:4bd8ed00bcb34f408351bb10be5fd3b7@thread.tacv2"
},
"attachments": [],
"mentions": [],
"reactions": [],
"eventDetail": {
"@odata.type": "#microsoft.graph.membersDeletedEventMessageDetail",
"members": [
{
"id": "1bb204d0-7fe2-4236-9359-9f331b4fa8e2",
"displayName": null,
"userIdentityType": "aadUser"
}
],
"initiator": {
"device": null,
"user": null,
"application": {
"id": "bb506fc1-8dec-422f-a2ff-5447575f1f78_90ab6497-27dd-4486-a98b-b7679d8e0d5d",
"displayName": null,
"applicationIdentityType": "aadApplication"
}
}
}
}
]
}
Error message variable: A variable to hold the error information from the call
Action Outputs:
Success
Failure
# List Channels
Action Function:
The List Channels action will return a list of channels for a specified Team.
Action Properties:
Scenario: The connection scenario to use for the action
Team ID: The Team ID to retrieve channels
Web timeout: An override timeout time in seconds to use for the call
Request status variable: A variable to hold the request status from the call
Response variable: A variable to hold the channel details response from the call. An example response is below.
{
"value": [
{
"createdDateTime": "2021-02-10T13:33:56.453Z",
"id": "19:4bd8ed00bcb34f408351bb10be5fd3b7@thread.tacv2",
"displayName": "General",
"description": "Test a connector",
"isFavoriteByDefault": null,
"email": "",
"webUrl": "https://teams.microsoft.com/l/channel/19%3a4bd8ed00bcb34f408351bb10be5fd3b7%40thread.tacv2/General?groupId=3082e20f-7b75-4465-b5e2-f76d1cf42a20&tenantId=bb506fc1-8dec-422f-a2ff-5447575f1f78",
"membershipType": "standard"
}
],
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#teams('3082e20f-7b75-4465-b5e2-f76d1cf42a20')/channels",
"@odata.count": 1
}
Error message variable: A variable to hold the error information from the call
Action Outputs:
Success
Failure
# List Team Apps
Action Function:
The List Team Apps action will return a list of Apps for a Team scenario.
Action Properties:
Scenario: The connection scenario to use for the action
Web timeout: An override timeout time in seconds to use for the call
Request status variable: A variable to hold the request status from the call
Response variable: A variable to hold the channel details response from the call
Error message variable: A variable to hold the error information from the call
Action Outputs:
Success
Failure
# List Teams
Action Function:
The List Teams action will return a list of Teams for a specified scenario.
Action Properties:
Scenario: The connection scenario to use for the action
Web timeout: An override timeout time in seconds to use for the call
Request status variable: A variable to hold the request status from the call
Response variable: A variable to hold the team details response from the call. Below is an example response.
{
"value": [
{
"id": "00f364c8-5986-4375-88ff-b96141329d18",
"displayName": "DnsAdmins",
"description": "DNS Administrators Group"
},
{
"id": "0bc69639-6a58-475a-b5aa-99cb5bcad4e6",
"displayName": "PMG Analytics",
"description": "PMG Analytics"
},
{
"id": "0c6a3c18-9c7c-4d57-a80e-53ba636f1e5f",
"displayName": "CSViewOnlyAdministrator",
"description": "Members of this group can view the Lync Server deployment, including server information, in order to monitor deployment health."
}
}
Error message variable: A variable to hold the error information from the call
Action Outputs:
Success
Failure
# Remove Team Member
Action Function:
The Remove Team Member action will remove a given membership ID from a Team
Action Properties:
Scenario: The connection scenario to use for the action
Team ID: The team to remove the member
Membership ID: The membership ID to remove
Web timeout: An override timeout time in seconds to use for the call
Response variable: A variable to hold the channel details response from the call
Error message variable: A variable to hold the error information from the call
Action Outputs:
Success
Failure
# Send Chat Message
Action Function:
The Send Chat Message action will send a message to a Team channel
Action Properties:
Scenario: The connection scenario to use for the action
Team ID: The Team ID to send the message
Channel ID: The Channel ID to send the message
Message content: The content of the message to send
Web timeout: An override timeout time in seconds to use for the call
Response variable: A variable to hold the channel details response from the call
Error message variable: A variable to hold the error information from the call
Action Outputs:
Success
Failure
# Update Channel
Action Function:
The Update Channel action will update a channel for a Team.
Action Properties:
Scenario: The connection scenario to use for the action
Team ID: The Team ID to use
Channel ID: The channel ID to update
Display name: The updated display name for the channel
Description: The updated description for the channel
Web timeout: An override timeout time in seconds to use for the call
Response variable: A variable to hold the response from the call
Error message variable: A variable to hold the error information from the call
Action Outputs:
Success
Failure